home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1993 July / InfoMagic USENET CD-ROM July 1993.ISO / sources / misc / volume19 / dmake / part13 < prev    next >
Encoding:
Text File  |  1991-05-11  |  40.4 KB  |  1,063 lines

  1. Newsgroups: comp.sources.misc
  2. From: Dennis Vadura <dvadura@watdragon.waterloo.edu>
  3. Subject:  v19i034:  dmake - dmake version 3.7, Part13/37
  4. Message-ID: <1991May10.185959.22840@sparky.IMD.Sterling.COM>
  5. Date: Fri, 10 May 1991 18:59:59 GMT
  6. Approved: kent@sparky.imd.sterling.com
  7.  
  8. Submitted-by: Dennis Vadura <dvadura@watdragon.waterloo.edu>
  9. Posting-number: Volume 19, Issue 34
  10. Archive-name: dmake/part13
  11. Supersedes: dmake-3.6: Volume 15, Issue 52-77
  12.  
  13. ---- Cut Here and feed the following to sh ----
  14. #!/bin/sh
  15. # this is dmake.shar.13 (part 13 of a multipart archive)
  16. # do not concatenate these parts, unpack them in order with /bin/sh
  17. # file dmake/man/dmake.nc continued
  18. #
  19. if test ! -r _shar_seq_.tmp; then
  20.     echo 'Please unpack part 1 first!'
  21.     exit 1
  22. fi
  23. (read Scheck
  24.  if test "$Scheck" != 13; then
  25.     echo Please unpack part "$Scheck" next!
  26.     exit 1
  27.  else
  28.     exit 0
  29.  fi
  30. ) < _shar_seq_.tmp || exit 1
  31. if test -f _shar_wnt_.tmp; then
  32. sed 's/^X//' << 'SHAR_EOF' >> 'dmake/man/dmake.nc' &&
  33. X                 once for the y.tab.h file.
  34. X
  35. X
  36. X     All attributes are user setable and except for .UPDATEALL,
  37. X     .SETDIR and .MKSARGS may be used in one of two forms.  The
  38. X     .MKSARGS attribute is restricted to use as a global attri-
  39. X     bute, and the use of the .UPDATEALL and .SETDIR attributes
  40. X     is restricted to rules of the second form only.
  41. X
  42. X          ATTRIBUTE_LIST : targets
  43. X
  44. X     assigns the attributes specified by ATTRIBUTE_LIST to each
  45. X     target in targets or
  46. X
  47. X          targets ATTRIBUTE_LIST : ...
  48. X
  49. X
  50. X
  51. Version 3.70                    UW                             11
  52. X
  53. X
  54. X
  55. X
  56. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  57. X
  58. X
  59. X
  60. X     assigns the attributes specified by ATTRIBUTE_LIST to each
  61. X     target in targets. In the first form if targets is empty
  62. X     (ie. a NULL list), then the list of attributes will apply to
  63. X     all targets in the makefile (this is equivalent to the com-
  64. X     mon Make construct of ".IGNORE :" but has been modified to
  65. X     the notion of an attribute instead of a special target).
  66. X     Not all of the attributes have global meaning.  In particu-
  67. X     lar, .LIBRARY, .SYMBOL, and .UPDATEALL have no assigned glo-
  68. X     bal meaning.
  69. X
  70. X     Any attribute may be used with any target, even with the
  71. X     special targets.  Some combinations are useless (e.g.
  72. X     .INCLUDE .PRECIOUS: ... ), while others are useful (e.g.
  73. X     .INCLUDE .IGNORE : "file.mk" will not complain if file.mk
  74. X     cannot be found using the include file search rules, see the
  75. X     section on SPECIAL TARGETS for a description of .INCLUDE).
  76. X     If a specified attribute will not be used with the special
  77. X     target a warning is issued and the attribute is ignored.
  78. X
  79. MACROS
  80. X     dmake supports six types of macro assignment.
  81. X
  82. X
  83. X     MACRO = LINE    This is the most common and familiar form of
  84. X                     macro assignment.  It assigns LINE literally
  85. X                     as the value of MACRO.  Future expansions of
  86. X                     MACRO recursively expand its value.
  87. X
  88. X     MACRO *= LINE   This form behaves exactly as the simple '='
  89. X                     form with the exception that if MACRO
  90. X                     already has a value then the assignment is
  91. X                     not performed.
  92. X
  93. X     MACRO := LINE   This form differs from the simple '=' form
  94. X                     in that it expands LINE prior to assigning
  95. X                     it as the value of MACRO.  Future expansions
  96. X                     of MACRO do not recursively expand its
  97. X                     value.
  98. X
  99. X     MACRO *:= LINE  This form behaves exactly as the ':=' form
  100. X                     with the exception that if MACRO already has
  101. X                     a value then the assignment and expansion
  102. X                     are not performed.
  103. X
  104. X     MACRO += LINE   This form of macro assignment allows macro
  105. X                     values to grow.  It takes the literal value
  106. X                     of LINE and appends it to the previous value
  107. X                     of MACRO separating the two by a single
  108. X                     space.  Future expansions of MACRO recur-
  109. X                     sively expand its value.
  110. X
  111. X
  112. X
  113. X
  114. X
  115. Version 3.70                    UW                             12
  116. X
  117. X
  118. X
  119. X
  120. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  121. X
  122. X
  123. X
  124. X     MACRO +:= LINE  This form is similar to the '+=' form except
  125. X                     that the value of LINE is expanded prior to
  126. X                     being added to the value of MACRO.
  127. X
  128. X     Macro expressions specified on the command line allow the
  129. X     macro value to be redefined within the makefile only if the
  130. X     macro is defined using the '+=' and '+:=' operators.  Other
  131. X     operators will define a macro that cannot be further modi-
  132. X     fied.
  133. X
  134. X     When dmake defines a non-environment macro it strips leading
  135. X     and trailing white space from the macro value.  Macros
  136. X     imported from the environment via either the .IMPORT special
  137. X     target (see the SPECIAL TARGETS section), or the -e, or -E
  138. X     flags are an exception to this rule.  Their values are
  139. X     always taken literally and white space is never stripped.
  140. X     In addition, named macros defined using the .IMPORT special
  141. X     target do not have their values expanded when they are used
  142. X     within a makefile.  In contrast, environment macros that are
  143. X     imported due to the specification of the -e or -E flags are
  144. X     subject to expansion when used.
  145. X
  146. X     To specify a macro expansion enclose the name in () or {}
  147. X     and precede it with a dollar sign $.  Thus $(TEST)
  148. X     represents an expansion of the macro variable named TEST.
  149. X     If TEST is defined then $(TEST) is replaced by its expanded
  150. X     value.  If TEST is not defined then $(TEST) expands to the
  151. X     NULL string (this is equivalent to defining a macro as
  152. X     'TEST=' ).  A short form may be used for single character
  153. X     named macros.  In this case the parentheses are optional,
  154. X     and $(I) is equivalent to $I.  Macro expansion is recursive,
  155. X     hence, if the value string contains an expression represent-
  156. X     ing a macro expansion, the expansion is performed.  Circular
  157. X     macro expansions are detected and cause an error to be
  158. X     issued.
  159. X
  160. X     When defining a macro the given macro name is first expanded
  161. X     before being used to define the macro.  Thus it is possible
  162. X     to define macros whose names depend on values of other mac-
  163. X     ros.  For example, suppose CWD is defined as
  164. X
  165. X          CWD = $(PWD:b)
  166. X
  167. X     then the value of $(CWD) is the name of the current direc-
  168. X     tory.  This can be used to define macros specific to this
  169. X     directory, for example:
  170. X
  171. X          _$(CWD).prt = list of files to print...
  172. X
  173. X     The actual name of the defined macro is a function of the
  174. X     current directory.  A construct such as this is useful when
  175. X     processing a hierarchy of directories using .SETDIR
  176. X
  177. X
  178. X
  179. Version 3.70                    UW                             13
  180. X
  181. X
  182. X
  183. X
  184. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  185. X
  186. X
  187. X
  188. X     attributed targets and a collection of small distributed
  189. X     makefile stubs.
  190. X
  191. X     Macro variables may be defined within the makefile, on the
  192. X     command line, or imported from the environment.
  193. X
  194. X     dmake supports several non-standard macro expansions: The
  195. X     first is of the form:
  196. X
  197. X          $(macro_name:modifier_list:modifier_list:...)
  198. X
  199. X     where modifier_list is chosen from the set { D or d, F or f,
  200. X     B or b, S or s, T or t } and
  201. X
  202. X          d - directory portion of all path names
  203. X          f - file (including suffix) portion of path names
  204. X          b - file (not including suffix) portion of path names
  205. X          s - simple pattern substitution
  206. X          t - tokenization.
  207. X
  208. X     Thus if we have the example:
  209. X
  210. X          test = d1/d2/d3/a.out f.out d1/k.out
  211. X
  212. X     The following macro expansions produce the values on the
  213. X     right of '-->' after expansion.
  214. X
  215. X          $(test:d)            --> d1/d2/d3/ d1/
  216. X          $(test:b)            --> a f k
  217. X          $(test:f)            --> a.out f.out k.out
  218. X          ${test:db}           --> d1/d2/d3/a f d1/k
  219. X          ${test:s/out/in/:f}  --> a.in f.in k.in
  220. X          $(test:f:t"+")       --> a.out+f.out+k.out
  221. X
  222. X     If a token ends in a string composed from the value of the
  223. X     macro DIRBRKSTR (ie. ends in a directory separator string,
  224. X     e.g. '/' in UNIX) and you use the :d modifier then the
  225. X     expansion returns the directory name less the final direc-
  226. X     tory separator string.  Thus successive pairs of :d modif-
  227. X     iers each remove a level of directory in the token string.
  228. X
  229. X     The tokenization modifier takes all white space separated
  230. X     tokens from the macro value and separates them by the quoted
  231. X     separator string.  The separator string may contain the fol-
  232. X     lowing escape codes \a => <bel>, \b => <backspace>, \f =>
  233. X     <formfeed>, \n => <nl>, \r => <cr>, \t => <tab>, \v =>
  234. X     <vertical tab>, \" => ", and \xxx => <xxx> where xxx is the
  235. X     octal representation of a character.  Thus the expansion:
  236. X
  237. X          $(test:f:t"+\n")
  238. X     produces:
  239. X          a.out+
  240. X
  241. X
  242. X
  243. Version 3.70                    UW                             14
  244. X
  245. X
  246. X
  247. X
  248. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  249. X
  250. X
  251. X
  252. X          f.out+
  253. X          k.out
  254. X
  255. X     The second non-standard form of macro expansion allows for
  256. X     recursive macros.  It is possible to specify a $(macro_name)
  257. X     or ${macro_name} expansion where macro_name contains more $(
  258. X     ... ) or ${ ... } macro expansions itself.
  259. X
  260. X     For example $(CC$(_HOST)$(_COMPILER)) will first expand
  261. X     CC$(_HOST)$(_COMPILER) to get a result and use that result
  262. X     as the name of the macro to expand.  This is useful for
  263. X     writing a makefile for more than one target environment.  As
  264. X     an example consider the following hypothetical case. Suppose
  265. X     that _HOST and _COMPILER are imported from the environment
  266. X     and are set to represent the host machine type and the host
  267. X     compiler respectively.
  268. X
  269. X          CFLAGS_VAX_CC = -c -O    # _HOST == "_VAX", _COMPILER == "_CC"
  270. X          CFLAGS_PC_MSC = -c -ML   # _HOST == "_PC",  _COMPILER == "_MSC"
  271. X
  272. X          # redefine CFLAGS macro as:
  273. X
  274. X          CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
  275. X
  276. X     This causes CFLAGS to take on a value that corresponds to
  277. X     the environment in which the make is being invoked.
  278. X
  279. X     The final non-standard macro expansion is of the form:
  280. X
  281. X          string1{token_list}string2
  282. X
  283. X     where string1, string2 and token_list are expanded.  After
  284. X     expansion, string1 is prepended to each token found in
  285. X     token_list and string2 is appended to each resulting token
  286. X     from the previous prepend.  string1 and string2 are not del-
  287. X     imited by white space whereas the tokens in token_list are.
  288. X     A null token in the token list is specified using "".  Thus
  289. X     using another example we have:
  290. X
  291. X          test/{f1 f2}.o     --> test/f1.o test/f2.o
  292. X          test/ {f1 f2}.o    --> test/ f1.o f2.o
  293. X          test/{f1 f2} .o    --> test/f1 test/f2 .o
  294. X          test/{"f1"  ""}.o  --> test/f1.o test/.o
  295. X
  296. X          and
  297. X
  298. X          test/{d1 d2}/{f1 f2}.o --> test/d1/f1.o test/d1/f2.o
  299. X                                     test/d2/f1.o test/d2/f2.o
  300. X
  301. X     This last expansion is activated only when the first charac-
  302. X     ters of token_list appear immediately after the opening '{'
  303. X     with no intervening white space.  The reason for this
  304. X
  305. X
  306. X
  307. Version 3.70                    UW                             15
  308. X
  309. X
  310. X
  311. X
  312. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  313. X
  314. X
  315. X
  316. X     restriction is the following incompatibility with Bourne
  317. X     Shell recipes.  The line
  318. X
  319. X          { echo hello;}
  320. X
  321. X     is valid /bin/sh syntax; while
  322. X
  323. X          {echo hello;}
  324. X
  325. X     is not.  Hence the latter triggers the enhanced macro expan-
  326. X     sion while the former causes it to be suppressed.  See the
  327. X     SPECIAL MACROS section for a description of the special mac-
  328. X     ros that dmake defines and understands.
  329. X
  330. RULES AND TARGETS
  331. X     A makefile contains a series of entries that specify depen-
  332. X     dencies.  Such entries are called target/prerequisite or
  333. X     rule definitions.  Each rule definition is optionally fol-
  334. X     lowed by a set of lines that provide a recipe for updating
  335. X     any targets defined by the rule.  Whenever dmake attempts to
  336. X     bring a target up to date and an explicit recipe is provided
  337. X     with a rule defining the target, that recipe is used to
  338. X     update the target.  A rule definition begins with a line
  339. X     having the following syntax:
  340. X
  341. X          <targets> [<attributes>] <ruleop> [<prerequisites>] [;<recipe>]
  342. X
  343. X     targets is a non-empty list of targets.  If the target is a
  344. X     special target (see SPECIAL TARGETS section below) then it
  345. X     must appear alone on the rule line.  For example:
  346. X
  347. X          .IMPORT .ERROR : ...
  348. X
  349. X     is not allowed since both .IMPORT and .ERROR are special
  350. X     targets.  Special targets are not used in the construction
  351. X     of the dependency graph and will not be made.
  352. X
  353. X     attributes is a possibly empty list of attributes.  Any
  354. X     attribute defined in the ATTRIBUTES section above may be
  355. X     specified.  All attributes will be applied to the list of
  356. X     named targets in the rule definition.  No other targets will
  357. X     be affected.
  358. X
  359. X
  360. X     NOTE:   As stated earlier, if both the target list and
  361. X             prerequisite list are empty but the attributes list
  362. X             is not, then the specified attributes affect all
  363. X             targets in the makefile.
  364. X
  365. X
  366. X     ruleop is a separator which is used to identify the targets
  367. X     from the prerequisites.  Optionally it also provides a
  368. X
  369. X
  370. X
  371. Version 3.70                    UW                             16
  372. X
  373. X
  374. X
  375. X
  376. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  377. X
  378. X
  379. X
  380. X     facility for modifying the way in which dmake handles the
  381. X     making of the associated targets.  In its simplest form the
  382. X     operator is a single ':', and need not be separated by white
  383. X     space from its neighboring tokens.  It may additionally be
  384. X     followed by any of the modifiers { !, ^, -, : }, where:
  385. X
  386. X
  387. X     !    says execute the recipe for the associated targets once
  388. X          for each out of date prerequisite.  Ordinarily the
  389. X          recipe is executed once for all out of date prere-
  390. X          quisites at the same time.
  391. X
  392. X     ^    says to insert the specified prerequisites, if any,
  393. X          before any other prerequisites already associated with
  394. X          the specified targets.  In general, it is not useful to
  395. X          specify ^ with an empty list of prerequisites.
  396. X
  397. X     -    says to clear the previous list of prerequisites before
  398. X          adding the new prerequisites.  Thus,
  399. X
  400. X               .SUFFIXES :
  401. X               .SUFFIXES : .a .b
  402. X
  403. X          can be replaced by
  404. X
  405. X               .SUFFIXES :- .a .b
  406. X
  407. X          however the old form still works as expected.  NOTE:
  408. X          .SUFFIXES is ignored by dmake it is used here simply as
  409. X          an example.
  410. X
  411. X     :    When the rule operator is not modified by a second ':'
  412. X          only one set of rules may be specified for making a
  413. X          target.  Multiple definitions may be used to add to the
  414. X          list of prerequisites that a target depends on.  How-
  415. X          ever, if a target is multiply defined only one defini-
  416. X          tion may specify a recipe for making the target.
  417. X
  418. X          When a target's rule operator is modified by a second
  419. X          ':' (:: for example) then this definition may not be
  420. X          the only definition with a recipe for the target.
  421. X          There may be other :: target definition lines that
  422. X          specify a different set of prerequisites with a dif-
  423. X          ferent recipe for updating the target. Any such target
  424. X          is made if any of the definitions find it to be out of
  425. X          date with respect to the related prerequisites and the
  426. X          corresponding recipe is used to update the target.
  427. X
  428. X          In the following simple example, each rule has a `::'
  429. X          ruleop.  In such an operator we call the first `:' the
  430. X          operator, and the second `:' the modifier.
  431. X
  432. X
  433. X
  434. X
  435. Version 3.70                    UW                             17
  436. X
  437. X
  438. X
  439. X
  440. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  441. X
  442. X
  443. X
  444. X          a.o :: a.c b.h
  445. X             first recipe for making a.o
  446. X
  447. X          a.o :: a.y b.h
  448. X             second recipe for making a.o
  449. X
  450. X          If a.o is found to be out of date with respect to a.c
  451. X          then the first recipe is used to make a.o.  If it is
  452. X          found out of date with respect to a.y then the second
  453. X          recipe is used.  If a.o is out of date with respect to
  454. X          b.h then both recipes are invoked to make a.o.  In the
  455. X          last case the order of invocation corresponds to the
  456. X          order in which the rule definitions appear in the
  457. X          makefile.
  458. X
  459. X     Targets defined using a single `:' operator with a recipe
  460. X     may be redefined again with a new recipe by using a `:'
  461. X     operator with a `:' modifier.  This is equivalent to a tar-
  462. X     get having been initially defined with a rule using a `:'
  463. X     modifier.  Once a target is defined using a `:' modifier it
  464. X     may not be defined again with a recipe using only the `:'
  465. X     operator with no `:' modifier.  In both cases the use of a
  466. X     `:' modifier creates a new list of prerequisites and makes
  467. X     it the current prerequisite list for the target.  The `:'
  468. X     operator with no recipe always modifies the current list of
  469. X     prerequisites.  Thus assuming each of the following defini-
  470. X     tions has a recipe attached, then:
  471. X
  472. X          joe :  fred ...     (1)
  473. X          joe :: more ...     (2)
  474. X
  475. X          and
  476. X
  477. X          joe :: fred ...     (3)
  478. X          joe :: more ...     (4)
  479. X
  480. X     are legal and mean:  add the recipe associated with (2), or
  481. X     (4) to the set of recipes for joe, placing them after exist-
  482. X     ing recipes for making joe.  The constructs:
  483. X
  484. X          joe :: fred ...     (5)
  485. X          joe : more ... (6)
  486. X
  487. X          and
  488. X
  489. X          joe : fred ... (7)
  490. X          joe : more ... (8)
  491. X
  492. X     are errors since we have two sets of perfectly good recipes
  493. X     for making the target.
  494. X
  495. X
  496. X
  497. X
  498. X
  499. Version 3.70                    UW                             18
  500. X
  501. X
  502. X
  503. X
  504. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  505. X
  506. X
  507. X
  508. X     prerequisites is a possibly empty list of targets that must
  509. X     be brought up to date before making the current target.
  510. X
  511. X     recipe is a short form and allows the user to specify short
  512. X     rule definitions on a single line.  It is taken to be the
  513. X     first recipe line in a larger recipe if additional lines
  514. X     follow the rule definition.  If the semi-colon is present
  515. X     but the recipe line is empty (ie. null string) then it is
  516. X     taken to be an empty rule.  Any target so defined causes the
  517. X     Don't know how to make ... error message to be suppressed
  518. X     when dmake tries to make the target and fails.  This silence
  519. X     is maintained for rules that are terminated by a semicolon
  520. X     and have no following recipe lines, for targets listed on
  521. X     the command line, for the first target found in the
  522. X     makefile, and for any target having no recipe but containing
  523. X     a list of prerequisites (see the COMPATIBILITY section for
  524. X     an exception to this rule if the AUGMAKE (-A) flag was
  525. X     specified.
  526. X
  527. RECIPES
  528. X     The traditional format used by most versions of Make defines
  529. X     the recipe lines as arbitrary strings that may contain macro
  530. X     expansions.  They follow a rule definition line and may be
  531. X     spaced apart by comment or blank lines.  The list of recipe
  532. X     lines defining the recipe is terminated by a new target
  533. X     definition, a macro definition, or end-of-file.  Each recipe
  534. X     line MUST begin with a <TAB> character which may optionally
  535. X     be followed with one or all of the characters '@%+-'.  The
  536. X     '-' indicates that non-zero exit values (ie. errors) are to
  537. X     be ignored when this recipe line is executed, the '+' indi-
  538. X     cates that the current recipe line is to be executed using
  539. X     the shell, the '%' indicates that dmake should swap itself
  540. X     out to secondary storage (MSDOS only) before running the
  541. X     recipe and the '@' indicates that the recipe line should NOT
  542. X     be echoed to the terminal prior to being executed.  Each
  543. X     switch is off by default (ie. by default, errors are signi-
  544. X     ficant, commands are echoed, no swapping is done and a shell
  545. X     is used only if the recipe line contains a character found
  546. X     in the value of the SHELLMETAS macro).  Global settings
  547. X     activated via command line options or special attribute or
  548. X     target names may also affect these settings.  An example
  549. X     recipe:
  550. X
  551. X          target :
  552. X               first recipe line
  553. X               second recipe line, executed independently of the first.
  554. X               @a recipe line that is not echoed
  555. X               -and one that has errors ignored
  556. X               %and one that causes dmake to swap out
  557. X               +and one that is executed using a shell.
  558. X
  559. X
  560. X
  561. X
  562. X
  563. Version 3.70                    UW                             19
  564. X
  565. X
  566. X
  567. X
  568. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  569. X
  570. X
  571. X
  572. X     The second and new format of the recipe block begins the
  573. X     block with the character '[' (the open group character) in
  574. X     the last non-white space position of a line, and terminates
  575. X     the block with the character ']' (the close group character)
  576. X     in the first non-white space position of a line.  In this
  577. X     form each recipe line need not have a leading TAB.  This is
  578. X     called a recipe group.  Groups so defined are fed intact as
  579. X     a single unit to a shell for execution whenever the
  580. X     corresponding target needs to be updated.  If the open group
  581. X     character '[' is preceded by one or all of -, @ or % then
  582. X     they apply to the entire group in the same way that they
  583. X     apply to single recipe lines.  You may also specify '+' but
  584. X     it is redundant as a shell is already being used to run the
  585. X     recipe.  See the MAKING TARGETS section for a description of
  586. X     how dmake invokes recipes.  Here is an example of a group
  587. X     recipe:
  588. X
  589. X          target :
  590. X          [
  591. X               first recipe line
  592. X               second recipe line
  593. X               all of these recipe lines are fed to a
  594. X               single copy of a shell for execution.
  595. X          ]
  596. X
  597. X
  598. TEXT DIVERSIONS
  599. X     dmake supports the notion of text diversions.  If a recipe
  600. X     line contains the macro expression
  601. X
  602. X          $(mktmp[,[file][,text]] data)
  603. X
  604. X     then all text contained in the data expression is expanded
  605. X     and is written to a temporary file.  The return value of the
  606. X     macro is the name of the temporary file.
  607. X
  608. X     data can be any text and must be separated from the 'mktmp'
  609. X     portion of the macro name by white-space.  The only restric-
  610. X     tion on the data text is that it must contain a balanced
  611. X     number of parentheses of the same kind as are used to ini-
  612. X     tiate the $(mktmp ...) expression.  For example:
  613. X
  614. X          $(mktmp $(XXX))
  615. X
  616. X     is legal and works as expected, but:
  617. X
  618. X          $(mktmp text (to dump to file)
  619. X
  620. X     is not legal.  You can achieve what you wish by either
  621. X     defining a macro that expands to '(' or by using {} in the
  622. X     macro expression; like this:
  623. X
  624. X
  625. X
  626. X
  627. Version 3.70                    UW                             20
  628. X
  629. X
  630. X
  631. X
  632. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  633. X
  634. X
  635. X
  636. X          ${mktmp text (to dump to file}
  637. X
  638. X     Since the temporary file is opened when the macro containing
  639. X     the text diversion expression is expanded, diversions may
  640. X     now be nested and any diversions that are created as part of
  641. X     ':=' macro expansions persist for the duration of the dmake
  642. X     run.  The diversion text may contain the same escape codes
  643. X     as those described in the MACROS section.  Thus if the data
  644. X     text is to contain new lines they must be inserted using the
  645. X     \n escape sequence.  For example the expression:
  646. X
  647. X          all:
  648. X               cat $(mktmp this is a\n\
  649. X               test of the text diversion\n)
  650. X
  651. X     is replaced by:
  652. X
  653. X          cat /tmp/mk12294AA
  654. X
  655. X     where the temporary file contains two lines both of which
  656. X     are terminated by a new-line.  If the data text spans multi-
  657. X     ple lines in the makefile then each line must be continued
  658. X     via the use of a \.  A second more illustrative example gen-
  659. X     erates a response file to an MSDOS link command:
  660. X
  661. X          OBJ = fred.obj mary.obj joe.obj
  662. X          all : $(OBJ)
  663. X               link @$(mktmp $(^:t"+\n")\n)
  664. X
  665. X     The result of making `all' in the second example is the com-
  666. X     mand:
  667. X
  668. X          link @/tmp/mk02394AA
  669. X
  670. X     where the temporary file contains:
  671. X
  672. X          fred.obj+
  673. X          mary.obj+
  674. X          joe.obj
  675. X
  676. X     The last line of the file is terminated by a new-line which
  677. X     is inserted due to the \n found at the end of the data
  678. X     string.
  679. X
  680. X     If the optional file specifier is present then its expanded
  681. X     value is the name of the temporary file to create.  Whenever
  682. X     a $(mktmp ...) macro is expanded the macro $(TMPFILE) is set
  683. X     to a new temporary file name.  Thus the construct:
  684. X
  685. X          $(mktmp,$(TMPFILE) data)
  686. X
  687. X     is completely equivalent to not specifying the $(TMPFILE)
  688. X
  689. X
  690. X
  691. Version 3.70                    UW                             21
  692. X
  693. X
  694. X
  695. X
  696. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  697. X
  698. X
  699. X
  700. X     optional argument.  Another example that would be useful for
  701. X     MSDOS users with a Turbo-C compiler
  702. X
  703. X          $(mktmp,turboc.cfg $(CFLAGS))
  704. X
  705. X     will place the contents of CFLAGS into a local turboc.cfg
  706. X     file.  The second optional argument, text, if present alters
  707. X     the name of the value returned by the $(mktmp ...) macro.
  708. X
  709. X     Under MS-DOS text diversions may be a problem.  Many DOS
  710. X     tools require that path names which contain directories use
  711. X     the \ character to delimit the directories.  Some users how-
  712. X     ever wish to use the '/' to delimit pathnames and use
  713. X     environments that allow them to do so.  The macro USESHELL
  714. X     is set to "yes" if the current recipe is forced to use a
  715. X     shell via the .USESHELL or '+' directives, otherwise its
  716. X     value is "no".  The dmake startup files define the macro
  717. X     DIVFILE whose value is either the value of TMPFILE or the
  718. X     value of TMPFILE edited to replace any '/' characters to the
  719. X     appropriate value based on the current shell and whether it
  720. X     will be used to execute the recipe.
  721. X
  722. X     Previous versions of dmake defined text diversions using <+,
  723. X     +> strings, where <+ started a text diversion and +> ter-
  724. X     minated one.  dmake is backward compatible with this con-
  725. X     struct if the <+ and +> appear literally on the same recipe
  726. X     line or in the same macro value string.  In such instances
  727. X     the expression:
  728. X
  729. X          <+data+>
  730. X
  731. X     is mapped to:
  732. X
  733. X          $(mktmp data)
  734. X
  735. X     which is fully output compatible with the earlier construct.
  736. X     <+, +> constructs whose text spans multiple lines must be
  737. X     converted by hand to use $(mktmp ...).
  738. X
  739. X     If the environment variable TMPDIR is defined then the tem-
  740. X     porary file is placed into the directory specified by that
  741. X     variable.  A makefile can modify the location of temporary
  742. X     files by defining a macro named TMPDIR and exporting it
  743. X     using the .EXPORT special target.
  744. X
  745. SPECIAL TARGETS
  746. X     This section describes the special targets that are recog-
  747. X     nized by dmake.  Some are affected by attributes and others
  748. X     are not.
  749. X
  750. X     .ERROR        If defined then the recipe associated with
  751. X                   this target is executed whenever an error
  752. X
  753. X
  754. X
  755. Version 3.70                    UW                             22
  756. X
  757. X
  758. X
  759. X
  760. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  761. X
  762. X
  763. X
  764. X                   condition is detected by dmake.  All attri-
  765. X                   butes that can be used with any other target
  766. X                   may be used with this target.  Any prere-
  767. X                   quisites of this target will be brought up to
  768. X                   date during its processing.  NOTE:  errors
  769. X                   will be ignored while making this target, in
  770. X                   extreme cases this may cause some problems.
  771. X
  772. X     .EXPORT       All prerequisites associated with this target
  773. X                   are assumed to correspond to macro names and
  774. X                   they and their values are exported to the
  775. X                   environment as environment strings at the
  776. X                   point in the makefile at which this target
  777. X                   appears.  Any attributes specified with this
  778. X                   target are ignored.  Only macros which have
  779. X                   been assigned a value in the makefile prior to
  780. X                   the export directive are exported, macros as
  781. X                   yet undefined are not exported.
  782. X
  783. X     .IMPORT       Prerequisite names specified for this target
  784. X                   are searched for in the environment and
  785. X                   defined as macros with their value taken from
  786. X                   the environment.  If the special name .EVERY-
  787. X                   THING is used as a prerequisite name then all
  788. X                   environment variables defined in the environ-
  789. X                   ment are imported.  The functionality of the
  790. X                   -e flag can be forced by placing the construct
  791. X                   .IMPORT : .EVERYTHING at the start of a
  792. X                   makefile.  Similarly, by placing the construct
  793. X                   at the end, one can emulate the effect of the
  794. X                   -E command line flag.  If a prerequisite name
  795. X                   cannot be found in the environment an error
  796. X                   message is issued.  .IMPORT accepts the
  797. X                   .IGNORE attribute.  When given, it causes
  798. X                   dmake to ignore the above error.  See the MAC-
  799. X                   ROS section for a description of the process-
  800. X                   ing of imported macro values.
  801. X
  802. X     .INCLUDE      Parse another makefile just as if it had been
  803. X                   located at the point of the .INCLUDE in the
  804. X                   current makefile.  The list of prerequisites
  805. X                   gives the list of makefiles to try to read.
  806. X                   If the list contains multiple makefiles then
  807. X                   they are read in order from left to right.
  808. X                   The following search rules are used when try-
  809. X                   ing to locate the file.  If the filename is
  810. X                   surrounded by " or just by itself then it is
  811. X                   searched for in the current directory.  If it
  812. X                   is not found it is then searched for in each
  813. X                   of the directories specified for the .INCLU-
  814. X                   DEDIRS special target.  If the file name is
  815. X                   surrounded by < and >, (ie.
  816. X
  817. X
  818. X
  819. Version 3.70                    UW                             23
  820. X
  821. X
  822. X
  823. X
  824. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  825. X
  826. X
  827. X
  828. X                   <my_spiffy_new_makefile>) then it is searched
  829. X                   for only in the directories given by the
  830. X                   .INCLUDEDIRS special target.  In both cases if
  831. X                   the file name is a fully qualified name start-
  832. X                   ing at the root of the file system then it is
  833. X                   only searched for once, and the .INCLUDEDIRS
  834. X                   list is ignored.  .INCLUDE accepts the .IGNORE
  835. X                   and .SETDIR attributes.  If .IGNORE attribute
  836. X                   is given and the file cannot be found then
  837. X                   dmake continues processing, otherwise an error
  838. X                   message is generated.  The .SETDIR attribute
  839. X                   causes dmake to change directories to the
  840. X                   specified directory prior to attempting the
  841. X                   include operation.
  842. X
  843. X     .INCLUDEDIRS  The list of prerequisites specified for this
  844. X                   target defines the set of directories to
  845. X                   search when trying to include a makefile.
  846. X
  847. X     .KEEP_STATE   This special target is a synonym for the macro
  848. X                   definition
  849. X
  850. X                        .KEEP_STATE := _state.mk
  851. X
  852. X                   It's effect is to turn on STATE keeping and to
  853. X                   define _state.mk as the state file.
  854. X
  855. X     .MAKEFILES    The list of prerequisites is the set of files
  856. X                   to try to read as the default makefile.  By
  857. X                   default this target is defined as:
  858. X
  859. X                        .MAKEFILES : makefile.mk Makefile
  860. X                   makefile
  861. X
  862. X
  863. X     .SOURCE       The prerequisite list of this target defines a
  864. X                   set of directories to check when trying to
  865. X                   locate a target file name.  See the section on
  866. X                   BINDING of targets for more information.
  867. X
  868. X     .SOURCE.suff  The same as .SOURCE, except that the
  869. X                   .SOURCE.suff list is searched first when try-
  870. X                   ing to locate a file matching the a target
  871. X                   whose name ends in the suffix .suff.
  872. X
  873. X     .REMOVE       The recipe of this target is used whenever
  874. X                   dmake needs to remove intermediate targets
  875. X                   that were made but do not need to be kept
  876. X                   around.  Such targets result from the applica-
  877. X                   tion of transitive closure on the dependency
  878. X                   graph.
  879. X
  880. X
  881. X
  882. X
  883. Version 3.70                    UW                             24
  884. X
  885. X
  886. X
  887. X
  888. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  889. X
  890. X
  891. X
  892. X     In addition to the special targets above, several other
  893. X     forms of targets are recognized and are considered special,
  894. X     their exact form and use is defined in the sections that
  895. X     follow.
  896. X
  897. SPECIAL MACROS
  898. X     dmake defines a number of special macros.  They are divided
  899. X     into three classes: control macros, run-time macros, and
  900. X     function macros.  The control macros are used by dmake to
  901. X     configure its actions, and are the preferred method of doing
  902. X     so.  In the case when a control macro has the same function
  903. X     as a special target or attribute they share the same name as
  904. X     the special target or attribute.  The run-time macros are
  905. X     defined when dmake makes targets and may be used by the user
  906. X     inside recipes.  The function macros provide higher level
  907. X     functions dealing with macro expansion and diversion file
  908. X     processing.
  909. X
  910. CONTROL MACROS
  911. X     To use the control macros simply assign them a value just
  912. X     like any other macro.  The control macros are divided into
  913. X     three groups: string valued macros, character valued macros,
  914. X     and boolean valued macros.
  915. X
  916. X     The following are all of the string valued macros.  This
  917. X     list is divided into two groups.  The first group gives the
  918. X     string valued macros that are defined internally and cannot
  919. X     be directly set by the user.
  920. X
  921. X     DIRBRKSTR     Contains the string of chars used to terminate
  922. X                   the name of a directory in a pathname.  Under
  923. X                   UNIX its value is "/", under MSDOS its value
  924. X                   is "/\:".
  925. X
  926. X     INCDEPTH      This macro's value is a string of digits
  927. X                   representing the current depth of makefile
  928. X                   inclusion.  In the first makefile level this
  929. X                   value is zero.
  930. X
  931. X     MFLAGS        Is the list of flags that were given on the
  932. X                   command line including a leading switch char-
  933. X                   acter.  The -f flag is not included in this
  934. X                   list.
  935. X
  936. X     MAKECMD       Is the name with which dmake was invoked.
  937. X
  938. X     MAKEDIR       Is the full path to the initial directory in
  939. X                   which dmake was invoked.
  940. X
  941. X     MAKEFILE      Contains the string "-f makefile" where,
  942. X                   makefile is the name of initial user makefile
  943. X                   that was first read.
  944. X
  945. X
  946. X
  947. Version 3.70                    UW                             25
  948. X
  949. X
  950. X
  951. X
  952. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  953. X
  954. X
  955. X
  956. X     MAKEFLAGS     Is the same as $(MFLAGS) but has no leading
  957. X                   switch character. (ie. MFLAGS = -$(MAKEFLAGS))
  958. X
  959. X     MAKEMACROS    Contains the complete list of macro expres-
  960. X                   sions that were specified on the command line.
  961. X
  962. X     MAKETARGETS   Contains the name(s) of the target(s), if any,
  963. X                   that were specified on the command line.
  964. X
  965. X     MAXPROCESSLIMIT
  966. X                   Is a numeric string representing the maximum
  967. X                   number of processes that dmake can use when
  968. X                   making targets using parallel mode.
  969. X
  970. X     NULL          Is permanently defined to be the NULL string.
  971. X                   This is useful when comparing a conditional
  972. X                   expression to an NULL value.
  973. X
  974. X     PWD           Is the full path to the current directory in
  975. X                   which make is executing.
  976. X
  977. X     TMPFILE       Is set to the name of the most recent tem-
  978. X                   porary file opened by dmake.  Temporary files
  979. X                   are used for text diversions and for group
  980. X                   recipe processing.
  981. X
  982. X     TMD           Stands for "To Make Dir", and is the path from
  983. X                   the present directory (value of $(PWD)) to the
  984. X                   directory that dmake was started up in (value
  985. X                   of $(MAKEDIR)).  This macro is modified when
  986. X                   .SETDIR attributes are processed.
  987. X
  988. X     USESHELL      The value of this macro is set to "yes" if the
  989. X                   current recipe is forced to use a shell for
  990. X                   its execution via the .USESHELL or '+' direc-
  991. X                   tives, its value is "no" otherwise.
  992. X
  993. X
  994. X     The second group of string valued macros control dmake
  995. X     behavior and may be set by the user.
  996. X
  997. X     .SETDIR         If this macro is assigned a value then dmake
  998. X                     will change to the directory given by that
  999. X                     value before making any targets.
  1000. X
  1001. X     AUGMAKE         If set to a non NULL value will enable the
  1002. X                     transformation of special meta targets to
  1003. X                     support special AUGMAKE inferences (See the
  1004. X                     COMPATIBILITY section).
  1005. X
  1006. X     DIRSEPSTR       Contains the string that is used to separate
  1007. X                     directory components when path names are
  1008. X
  1009. X
  1010. X
  1011. Version 3.70                    UW                             26
  1012. X
  1013. X
  1014. X
  1015. X
  1016. DMAKE(p)             Unsupported Free Software            DMAKE(p)
  1017. X
  1018. X
  1019. X
  1020. X                     constructed.  It is defined with a default
  1021. X                     value at startup.
  1022. X
  1023. X     DIVFILE         Is defined in the startup file and gives the
  1024. X                     name that should be returned for the diver-
  1025. X                     sion file name when used in $(mktmp ...)
  1026. X                     expansions, see the TEXT DIVERSION section
  1027. X                     for details.
  1028. X
  1029. X     .KEEP_STATE     Assigning this macro a value tells dmake the
  1030. X                     name of the state file to use and turns on
  1031. X                     the keeping of state information for any
  1032. X                     targets that are brought up to date by the
  1033. X                     make.
  1034. X
  1035. X     GROUPFLAGS      This macro gives the set of flags to pass to
  1036. X                     the shell when invoking it to execute a
  1037. X                     group recipe.  The value of the macro is the
  1038. X                     list of flags with a leading switch indica-
  1039. X                     tor.  (ie. `-' under UNIX)
  1040. X
  1041. X     GROUPSHELL      This macro defines the full path to the exe-
  1042. X                     cutable image to be used as the shell when
  1043. X                     processing group recipes.  This macro must
  1044. X                     be defined if group recipes are used.  It is
  1045. X                     assigned a default value in the startup
  1046. X                     makefile.  Under UNIX this value is /bin/sh.
  1047. X
  1048. X     GROUPSUFFIX     If defined, this macro gives the string to
  1049. X                     use as a suffix when creating group recipe
  1050. SHAR_EOF
  1051. true || echo 'restore of dmake/man/dmake.nc failed'
  1052. fi
  1053. echo 'End of part 13, continue with part 14'
  1054. echo 14 > _shar_seq_.tmp
  1055. exit 0
  1056.  
  1057. exit 0 # Just in case...
  1058. -- 
  1059. Kent Landfield                   INTERNET: kent@sparky.IMD.Sterling.COM
  1060. Sterling Software, IMD           UUCP:     uunet!sparky!kent
  1061. Phone:    (402) 291-8300         FAX:      (402) 291-4362
  1062. Please send comp.sources.misc-related mail to kent@uunet.uu.net.
  1063.